Apple WWDC 1996

home *** CD-ROM | disk | FTP | other *** search

/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Framework / Includes / UEventHandler.h < prev next >

Wrap

Text File | 1996-04-03 | 14.5 KB | 399 lines | [TEXT/MPS ]

// UEventHandler.h // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved. #ifndef __UEVENTHANDLER__ #define __UEVENTHANDLER__ // MacApp #ifndef __GEOMETRY__ #include "Geometry.h" #endif #ifndef __UITERATOR__ #include "UIterator.h" #endif #ifndef __UOBJECT__ #include "UObject.h" #endif // Toolbox //---------------------------------------------------------------------------------------- // Some miscellaneous declarations. //---------------------------------------------------------------------------------------- enum IdlePhase { idleBegin, idleContinue, idleEnd }; //---------------------------------------------------------------------------------------- // Forward and external class declarations. //---------------------------------------------------------------------------------------- class TBehavior; class TCommand; class TEvent; class TToolboxEvent; class TWindow; //---------------------------------------------------------------------------------------- // TEventHandler: This type represents abstract objects that handle certain kinds of events: // Key events: both key down and auto key events, menu events: both enabling menus and // menu items and processing menu commands, Read to/ write from Disk, Idle events: when // there are no other events to handle, Actual events: EvtHandlers - through their method // 'DoHandleEvent' may intercept and handle actual ToolBox events Termination: when the // application quits TEventHandler are linked into a list with the most specific object // (usually a selection) at the head of the list. 'TApplication->fTarget' contains the head // of the list. (When a window is deactivated, this global variable is cached in the // window object, and retrieved when it is later activated.) For these kinds of events, // the TApplication->fTarget gets the first crack at handling the event. The default // implementation of the methods of TEventHandler is to pass the event to the next element // of the list. //---------------------------------------------------------------------------------------- class TEventHandler : public TObject { MA_DECLARE_CLASS; public: //------------------------------------------------------------------------------------ // Initializer, I<Method> and Free. //------------------------------------------------------------------------------------ TEventHandler(); // Constructor void IEventHandler(TEventHandler* itsNextHandler); // Call IObject and set fNextHandler to itsNextHandler. virtual ~TEventHandler(); // Before calling Inherited::Free, changes the target to the application if the // next handler is NULL or the next handler if there is one. virtual TObject* Clone(); // Calls Inherited::Clone and then clones owned objects. //------------------------------------------------------------------------------------ // Termination //------------------------------------------------------------------------------------ virtual void Terminate(); // Does nothing in this class. //------------------------------------------------------------------------------------ // Stream I/O protocol support. //------------------------------------------------------------------------------------ virtual void ReadFrom(TStream* aStream); virtual void WriteTo(TStream* aStream); //------------------------------------------------------------------------------------ // Chainwalking //------------------------------------------------------------------------------------ inline TEventHandler* GetNextHandler() const { return fNextHandler; } // Return the next handler in the chain TEventHandler* AddHandler(TEventHandler* headOfChain); // Adds this from the chain of handlers starting at headOfChain. Returns the new // head of chain. TEventHandler* RemoveHandler(TEventHandler* headOfChain); // Removes this from the chain of handlers starting at headOfChain. Returns the // new head of chain (if this was the head then there _must_ be a new head. //------------------------------------------------------------------------------------ // Events //------------------------------------------------------------------------------------ long NextIdle(); // Returns the number Tickcount for when the handler should next be idled. void HandleIdle(IdlePhase phase); // Calls DoIdle if the handler is eligible. virtual Boolean DoIdle(IdlePhase phase); // Returns true if it frees itself so caller can know virtual Boolean DoCoHandlerEvent(TEvent* event); // Handle the event and return true if I want it, else I don't handle it, and // return false virtual void DoEvent(EventNumber eventNumber, TEventHandler* source, TEvent* event); // By default, asks the next handler to handle the event virtual void HandleEvent(EventNumber eventNumber, TEventHandler* source, TEvent* event); // Responsible for dispatching DoHandleEvent messages virtual void SetEnable(Boolean state); // Enables based on 'state' inline Boolean IsEnabled() const { return fEnabled; } // Returns the enabled state. //------------------------------------------------------------------------------------ // Double/ Triple Clicks //------------------------------------------------------------------------------------ virtual Boolean DoMultiClick(CPoint lastDownPt, CPoint newDownPt); // Called by TApplication::CountClicks. Should return true if the 2 points are // close enough to be considered part of a double/ triple click. (Both points are // in global coordinates.) This is only called if the mouse down was within the // proper time range of the previous mouse up. Default is to pass message to the // nextEventHandler (if one exists), otherise to require that the sum of the x & y // distances is <= gStdHysteresis. //------------------------------------------------------------------------------------ // Key Events //------------------------------------------------------------------------------------ virtual void DoKeyEvent(TToolboxEvent* event); // Handles all keystrokes except those with the command key held down. virtual void DoKeyUp(TToolboxEvent* event); // Handles all key upstrokes. void HandleKeyCommand(TToolboxEvent* event); // Handles the dispatching of DoKeyEvent messages between itself and Behaviors void HandleKeyUp(TToolboxEvent* event); // Handles the dispatching of DoKeyUp messages between itself and Behaviors virtual void DoCommandKeyEvent(TToolboxEvent* event); // Handles command-key combinations only. void HandleCommandKey(TToolboxEvent* event); // Handles the dispatching of DoCommandKeyEvent messages between itself and Behaviors virtual void KeyEventToComponents(TToolboxEvent* event); // Intended to extract character components of an event in a script manager // compatible way.Default just forwards to next handler //------------------------------------------------------------------------------------ // MenuEvents //------------------------------------------------------------------------------------ virtual void DoMenuCommand(CommandNumber aCommandNumber); // If the handler can perform the command it does so by either performing the // command directly or by posting a TCommand. void HandleMenuCommand(CommandNumber aCommandNumber); // Handles the dispatching of DoMenuCommand messages virtual void DoSetupMenus(); // Handles the setup of menus. virtual void HandleSetupMenus(); // Handles the dispatching of DoSetupMenus messages //------------------------------------------------------------------------------------ // Help //------------------------------------------------------------------------------------ virtual void DoHelp(TToolboxEvent* event, long& message); // If fNextHandler is not NULL calls its DoHelp method, otherwise returns NULL. //------------------------------------------------------------------------------------ // Target management //------------------------------------------------------------------------------------ virtual TWindow *GetWindow() const; // returns the TWindow of this TEventHandler (if any). Returns NULL if this TEventHandler isn't a TView // or isn't installed in a TWindow. virtual Boolean WantsToBeTarget(); // Called to find out if this object wishes to become the target. Default returns // false virtual long WillingToResignTarget(); // Called to find out if this object is willing to cease being the target. Default // returns true virtual void TargetValidationSucceeded(); virtual void TargetValidationFailed(long reason); virtual void BecameWindowTarget(); // Called when this object becomes the current target of a window virtual void ResignedWindowTarget(); // Called when this object ceases to be the current target of a window virtual void BecameTarget(); // Called when this object becomes the current target virtual void ResignedTarget(); // Called when this object ceases to be the current target virtual Boolean BecomeTarget(); // Called to make this object be the current target virtual Boolean ResignTarget(); // Called to inform this object to cease being the current target virtual void SetTargetSelection(Boolean redraw); // Called when this object becomes the target, except as a result of a mouse click // Overridden by EditTexts to select all characters virtual Boolean IsTarget(); // Returns true when this object is the current target //------------------------------------------------------------------------------------ // Miscellaneous //------------------------------------------------------------------------------------ virtual void DoKeySelection(const CStr255& selectionString); // Derived classes override this method to set the selection based on the value of // 'selectionString'. This method is called by a TKeySelectionBehavior which can // be added to a TEventHandler and any of its derived classes. inline IDType GetIdentifier() const { return fIdentifier; } // Return the fIdentifier of the object. inline long GetIdleFreq() const { return fIdleFreq; } // Return the current value of fIdleFreq. virtual void SetIdleFreq(long newIdleFreq); // Call to set the handler's idling frequency. void RemoveBehavior (TBehavior* theBehavior); // Remove theBehavior from the behavior chain void AddBehavior (TBehavior* theBehavior); // Call to add theBehavior to this object inline TBehavior* GetFirstBehavior() const { return fBehavior; } // Call to retrieve the first behavior currently attached to EvtHandler TBehavior* GetFirstEnabledBehavior () const; // Call to retrieve the first enabled behavior currently attached to EvtHandler virtual TBehavior* GetBehaviorWithIdentifier(IDType itsIdentifier); // Returns the first behavior with the specified ID, or NULL virtual void SelectOwner (Boolean select); // "Selects" this object by calling the SelectOwner method of each behavior virtual Boolean IsSelected(); // Returns the value of the first behavior's IsOwnerSelected(), or false // if there are no behaviors virtual void DoUpdate(ChangeID theChange, TObject* changedObject, TObject* changedBy, TDependencySpace* dependencySpace); // Override //------------------------------------------------------------------------------------ // Command Management //------------------------------------------------------------------------------------ virtual TEvent* RetrieveAnEvent(); // Retrieves a previously posted event/ command from the queue. NULL if there are no // queued commands. Default is to hand off to fNextHandler virtual void PostAnEvent(TEvent* event); // Called to post an event or command to a queue for later processing. Default is // to hand off to fNextHandler virtual void PostCommand(TCommand* command); // Called to post a command to a queue for later execution. Left in for // compatibility - calls PostAnEvent //------------------------------------------------------------------------------------ // data members //------------------------------------------------------------------------------------ public: TEventHandler* fNextHandler; // the next element of the list, or NULL TBehavior* fBehavior; // Behavioral modifier object IDType fIdentifier; // the ID if any long fIdleFreq; // the minimum number of ticks that can // pass before my DoIdle is called. 0 = // call as often as possible. // n..kMaxIdleTime = call every fIdleFreq // ticks. long fLastIdle; // the tick count the last time my DoIdle // was called. Boolean fEnabled; // is this eventHandler enabled. (does it // take clicks/keystrokes and other // events? //---------------------------------------------------------------------------------------- // static data members //---------------------------------------------------------------------------------------- public: static CPoint gStdHysteresis; // standard hysteresis used in TCommand::ICommand }; //---------------------------------------------------------------------------------------- // CHandlerIterator: A simple iterator for the handler chain. //---------------------------------------------------------------------------------------- class CHandlerIterator { public: CHandlerIterator(TEventHandler* chainHead); inline Boolean More() // override { return (fCurrentHandler != NULL); } // Returns true if there are more elements to iterate over inline void Reset() // override { fCurrentHandler = fFirstHandler; } // Resets the iterator to begin again inline TEventHandler* CurrentHandler() { return fCurrentHandler; } // returns the current handler in the handler chain TEventHandler* FirstHandler(); // Resets the iterator to begin again and returns the first handler in the handler chain TEventHandler* NextHandler(); // returns the next handler in the handler chain protected: void Advance(); // override // Advances the iteration //------------------------------------------------------------------------------------ // data members //------------------------------------------------------------------------------------ private: TEventHandler* fFirstHandler; TEventHandler* fCurrentHandler; TEventHandler* fNextHandler; }; #endif